package com.example.rssreader.service;

import com.example.rssreader.common.PageResponse;
import com.example.rssreader.dto.ArticleResponse;

import java.util.List;

/**
 * 文章服务接口
 * 定义文章相关的业务操作
 * 
 * @author RSS Reader Team
 * @version 1.0.0
 * @since 2024-01-01
 */
public interface ArticleService {

    /**
     * 分页查询文章列表
     * 
     * @param page   页码，从1开始
     * @param size   每页大小
     * @param feedId RSS源ID，可选参数，为null时查询所有RSS源的文章
     * @param isRead 是否已读，可选参数，为null时查询所有状态的文章
     * @return 分页响应结果
     */
    PageResponse<ArticleResponse> getArticles(Integer page, Integer size, Long feedId, Boolean isRead);

    /**
     * 根据ID获取文章详情
     * 包含完整的文章内容
     * 
     * @param id 文章ID
     * @return 文章响应信息
     * @throws RuntimeException 当文章不存在时抛出异常
     */
    ArticleResponse getArticleById(Long id);

    /**
     * 标记文章为已读
     * 
     * @param id 文章ID
     * @throws RuntimeException 当文章不存在时抛出异常
     */
    void markAsRead(Long id);

    /**
     * 标记文章为未读
     * 
     * @param id 文章ID
     * @throws RuntimeException 当文章不存在时抛出异常
     */
    void markAsUnread(Long id);

    /**
     * 批量标记文章为已读
     * 
     * @param articleIds 文章ID列表
     * @return 成功标记的文章数量
     */
    Integer batchMarkAsRead(List<Long> articleIds);

    /**
     * 标记RSS源下所有文章为已读
     * 
     * @param feedId RSS源ID
     * @return 成功标记的文章数量
     * @throws RuntimeException 当RSS源不存在时抛出异常
     */
    Integer markFeedArticlesAsRead(Long feedId);

    /**
     * 搜索文章
     * 根据关键词在标题、描述和内容中进行模糊搜索
     * 
     * @param keyword 搜索关键词
     * @param page    页码，从1开始
     * @param size    每页大小
     * @param feedId  RSS源ID，可选参数，为null时在所有RSS源中搜索
     * @return 分页响应结果
     */
    PageResponse<ArticleResponse> searchArticles(String keyword, Integer page, Integer size, Long feedId);

    /**
     * 获取未读文章数量
     * 
     * @param feedId RSS源ID，可选参数，为null时统计所有RSS源的未读文章
     * @return 未读文章数量
     */
    Long getUnreadCount(Long feedId);

    /**
     * 获取最新文章
     * 
     * @param limit 限制数量，默认10条
     * @return 最新文章列表
     */
    List<ArticleResponse> getLatestArticles(Integer limit);

    /**
     * 删除文章
     * 逻辑删除
     * 
     * @param id 文章ID
     * @throws RuntimeException 当文章不存在时抛出异常
     */
    void deleteArticle(Long id);

    /**
     * 批量删除文章
     * 逻辑删除
     * 
     * @param articleIds 文章ID列表
     * @return 成功删除的文章数量
     */
    Integer batchDeleteArticles(List<Long> articleIds);

    /**
     * 清理旧文章
     * 删除指定天数之前的文章
     * 
     * @param daysAgo 天数，删除多少天前的文章
     * @return 清理的文章数量
     */
    Integer cleanOldArticles(Integer daysAgo);

    /**
     * 获取文章统计信息
     * 
     * @param feedId RSS源ID，可选参数，为null时统计所有RSS源
     * @return 统计信息，包括总数、未读数量、今日新增等
     */
    Object getArticleStatistics(Long feedId);

    /**
     * 标记所有文章为已读
     * 
     * @return 成功标记的文章数量
     */
    Integer markAllAsRead();
}